/*	
   ______   ______    
  /\__  __\/\ \___\ 
  \/_/\ \_/\ \ \__/    __   __     __       
     \ \ \  \ \ \__\  /\ \ /\ \  /'__`\  
     _\_\ \  \ \ \_/_ \ \ \\_\ \/\  __/       
    /\____/   \ \_____\\ \_____/\ \____\   
    \_/__/     \/_____/ \/____/  \/____/                   
 
 	This file is part of the JEVE core API.

    JEve is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.

    JEve is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    
    Copyright 2008 JEve Project (JEveProject@gmail.com)
 */
package be.fomp.jeve.core.api;

import be.fomp.jeve.core.exceptions.JEveConnectionException;
import be.fomp.jeve.core.exceptions.JEveParseException;
import org.jdom.Document;

import java.awt.*;

/**
 * <pre>
 *  ______   ______
 * /\__  __\/\ \___\
 * \/_/\ \_/\ \ \__/    __   __     __
 *    \ \ \  \ \ \__\  /\ \ /\ \  /'__`\
 *    _\_\ \  \ \ \_/_ \ \ \\_\ \/\  __/
 *   /\____/   \ \_____\\ \_____/\ \____\
 *   \_/__/     \/_____/ \/____/  \/____/
 * </pre>
 * This file is part of the JEVE core API.<br />
 * <br />
 * <p/>
 * Interface containing the accessor methods for the EVE-Online API
 * which do not require an API key.
 *
 * @author Sven Meys
 * @version 1.0
 */
public interface StandardAPI {

	/*--[ API V1 ]--*/

	/**
	 * This method retrieves the alliance list from
	 * http://api.eve-online.com/eve/AllianceList.xml.aspx.
	 *
	 * @return A list of alliances in eve.
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getAllianceList() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a list of solarsystems and
	 * what faction or alliance controls them
	 * from http://api.eve-online.com/map/Sovereignty.xml.aspx.
	 *
	 * @return A list of solarsystems and what faction or alliance controls them
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getSovereignty() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves the character ID(s) of the corresponding
	 * names from http://api.eve-online.com/eve/CharacterID.xml.aspx.
	 *
	 * @param names Comma separated list of character names
	 * @return The ID('s) of a given character name or names
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getCharacterID(String names) throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a portrait from the
	 * corresponding character from http://img.eve.is/serv.asp.
	 *
	 * @param size		The expected size of the image, can only be 64 or 256.
	 *                    If the given size is not one of these values, the existing value will be rounded.
	 *                    If the size is smaller than the average of both values it will be defaulted to 64,
	 *                    otherwise to 128.
	 * @param characterID the character ID
	 * @return A character portrait
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Image getPortrait(int size, int characterID) throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a list of transaction types used in the Journal Entries
	 * from http://api.eve-online.com/eve/RefTypes.xml.aspx.
	 *
	 * @return A list of transaction types used in the Journal Entries.
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getRefTypes() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a list of all skills in eve
	 * from http://api.eve-online.com/eve/SkillTree.xml.aspx.
	 *
	 * @return A list of all skills
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getSkillTree() throws JEveConnectionException, JEveParseException;

	/*--[ API V2 ]--*/

	/**
	 * This method retrieves the list of conquerable stations from
	 * http://api.eve-online.com/eve/ConquerableStationList.xml.aspx.
	 *
	 * @return A list of conquerable stations in eve
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getConquerableStationList() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a corporation sheet if the given
	 * corporation belongs to an alliance from
	 * http://api.eve-online.com/corp/CorporationSheet.xml.aspx.
	 *
	 * @param userID		The user ID
	 * @param corporationID The corporation ID
	 * @return A corporation sheet
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getCorporationSheet(int userID, int corporationID) throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves an list of errors generated by
	 * the eve API from http://api.eve-online.com/eve/ErrorList.xml.aspx.
	 *
	 * @return A list of errors
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getErrorList() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves an list jumps in eve
	 * from http://api.eve-online.com/map/Jumps.xml.aspx.
	 * <p/>
	 * Note that only systems with jumps are shown,
	 * if the system has no jumps, it's not listed.
	 *
	 * @return A list of jumps
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getJumps() throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves a list kills in eve
	 * from http://api.eve-online.com/map/Kills.xml.aspx.
	 * <p/>
	 * Note that only systems with kills are shown,
	 * if the system has no kills, it's not listed.
	 *
	 * @return A list of kills
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getKills() throws JEveConnectionException, JEveParseException;

	/*--[ API V3 ]--*/

	//Not out yet....
}
